Network CD 1/Network CD.iso/tbag/1-10/tb6/doc-files/cli-doc/sili.doc

Text File | 1985-11-26 | 21KB | 443 lines

                                                                   [8611.2]
                             First Sili(Con:)
                             ________________


                            -- the Smart CLI --


                        Copyright (C)1986 Pete Goodeve
                        (for distribution conditions,
                         see the end of this document.)


This is the first release of Sili(Con:), a greatly enhanced CLI for
AmigaDOS.  [yes, you're right -- it is an acronym of sorts...  It's a
"Smart Input Line Interpreter", with its own "Control Console" window.
Also I just kind of like silly names...]

Unlike the normal CLI, Sili(Con:) accepts DOS commands in a window
of their own, with full editing facilities -- cursor positioning with the
arrow keys, backspace left, delete right, and so on.  The program invoked
by the command runs in the normal CLI Console window; any direct interaction
with the program also takes place in this window.

A "History" of previous commands is maintained in the Command window.
You can use the up and down arrow keys to bring any of these back for
re-execution or re-editing.  You can also click on any visible command
with the mouse to bring it back, or double-click to execute it. (More
commands than are visible remain accessible with the arrow keys, but
this first release has no way of paging them onto the screen, except
by making the window larger.)

Other keystrokes -- described in detail below -- allow you to delete items
from the history list, or add new ones without actually executing them.
You can also activate the command window and bring it to the front with a
keystroke, or quickly push it out of the way so the entire screen becomes
visible.  You can work in the Control window at any time, even when a
program is currently executing in the Console window: all the commands
that you enter will be executed in sequence.

The Command Interpreter itself is also enhanced.  It checks the invoked
command to see if it is a command script rather than a program: if it is,
and takes no arguments, it will execute the commands in the script itself;
if it is an "EXECUTE" type file, it will invoke the EXECUTE command
-- renamed "X" in this release -- to interpret the arguments and commands.
Other enhancements, including an "append" version of output redirection,
are described below.

This software is donation supported.  Please read the Distribution
information and conditions at the end of this document.


Limitations
===========

Let's get these out of the way first, so we know where we stand.

First, this release only works with Workbench 1.2 (now supposedly available
as of this writing).  It was originally intended to be useable under 1.1
as well, but it would never be as convenient without the functions of 1.2
that it is able to use; in addition, there is some problem at the moment
that makes it completely useless under 1.1.  Sorry.

Although it is perfectly possible to have a copy of Sili(Con:) in each
CLI window you have open, each copy takes up about 32K (program plus
workspace), so you probably will not want to do this.  Also you may get
confused as to which Control window goes with which Program window, and
furthermore the "awaken" keystroke will only work with the one you started
first (though you can always use the mouse to awaken others).  This
limitation is eased considerably by the ability to set up script files which
automatically "RUN" programs such as editors, leaving the Control window
available for further commands.  You can also invoke as many commands as
you want at any time: they will be executed in sequence.

I have tried to make the NEED to use the mouse as small as possible
(although it is often very convenient, and the option is always available),
but there are times at which there is no alternative to its use; in
particular, if you want to interact with the running program you will have
to click in that window (unless the program has opened and activated its
own).  Note too that if you are in the middle of typing a command when
a program opens a window, the new window won't become active automatically.
On the other hand, if you leave the mouse pointer in a convenient position
you can "click" the left button with the Left-Amiga-ALT key combination.

Remember that when Sili(Con:) is running you don't type commands into the
associated CLI Console window!  Anything you DO type into that window when
no program is waiting for it will simply remain there until some later
program reads from the Console.  As usual though, typing characters into
the window will stop any more output showing in that window until they're
cleared.

A final point: you can of course say "RUN commandname" to Sili(Con:),
but RUN is simply a standard CLI, and doesn't know about any of Sili(Con:)'s
added features.

And now on to the good stuff.


Installing and Running Sili(Con:)
================================

The executable program is actually called "sili" for simplicity.  You should
install it in your "C:" directory like any other DOS command.  Start it
simply by giving the command "sili" to your DOS CLI; it takes over
management of the CLI window it was invoked from until you terminate it
again.

For proper operation in all circumstances, you will also have to rename
(or copy, if you prefer) the DOS "EXECUTE" command to "X", as this is the
name that Sili(Con:) expects for this program when it needs it.  This module
is only used if you give Sili(Con:) a command invoking a script file with
arguments; otherwise the program is totally self-contained.

You may also want to edit your "startup-sequence" file in the "S:" directory
to execute "sili" as its final command, so that it becomes your standard
interface to the system.  If you don't mind the memory space being occupied,
you might also like to have your startup-sequence create a directory RAM:C,
say, and transfer some frequently used command files to it. It should also
add this directory to your path (see below), so that Sili(Con:) can find
them.  This satisfies two major desires: things run faster, and you can do
a lot of things without your system disk in the drive.  The DOS 1.2 "path"
-- which Sili(Con:) takes full advantage of -- is a notable improvement in
the flexibility of the system.


Closing Down
============

To remove Sili(Con:) from the system, click on the "Close" box.  You will
return to the standard CLI after any commands in progress have completed.

You may get confused if you give the "ENDCLI" command  to Sili(Con:).
It will be ignored until you click in the close box, at which point both
Sili(Con:) and the CLI window itself will terminate.


Command Search Path
===================

Sili(Con:) is aware of, and uses, AmigaDOS 1.2's command file "path".
However, unlike the CLI, it will find both program and script-file commands
on that path (with restrictions noted below).  In addition, you can assign
certain special "logical device names" to directories that Sili(Con:) will
also search.  If some of the directories you've specified in the path or as
logical devices are not at the moment available (because you've removed the
disk containing them) Sili(Con:) ignores them in its search.

For those new to release 1.2 of DOS, the path is a list of directories
that will be searched -- after the current directory, and before the "C:"
directory -- for a filename that matches the command; the first one found
will be executed.  You set up (and list) the path with the DOS "PATH"
command.  See the 1.2 documentation for full details.

Sili(Con:) also searches directories ("logical devices") "C0:", "C1:",
"C2:", "C3:", and "C4:" if they exist.  "C0:" is searched BEFORE your
current directory; the others are searched, in order, after the current
directory but before the path and the "S:" and "C:" directories.
Use the "ASSIGN" command to assign these special names to the particular
directories you want to search.  As an example, if you have some commands
in "RAM:C" and others in "DF1:UTIL", you can make them accessible by:

          ASSIGN C1: RAM:C
          ASSIGN C2: DF1:UTIL

Alternatively you can use a path:

          PATH RAM:C DF1:UTIL

The advantage of the first method is that you can easily reassign one
directory without affecting others (after changing work disks for example)
-- also it is required for some command script files (see below).
The advantage of the second is that you don't have to be concerned as to
which slots are already in use.  My approach is to set up the path (to RAM:C
etc) with the startup-sequence and then leave it alone, and to have a "use"
command script in the root directory of each work disk that I invoke when
I insert the disk, which sets up C1: etc. as specific command directories
for that disk.


Command Script Files
====================

You do not normally have to explicitly use the "EXECUTE" command with
Sili(Con:).  If you give a command which is in fact the name of a script
file, it will be executed directly.  Sili(Con:) will attempt to interpret it
itself as a simple sequence of DOS commands, unless the first non-blank
line begins with a period.  In this case, it assumes that the file expects
command line arguments to be substituted into the text, and calls "X"
(the "EXECUTE" command renamed) to process it.

If a command script is one that Sili(Con:) must run via the 'X' command
it should NOT be in the DOS 1.2 Search Path: it must be in the current
directory, the "S:" (or "C:") directory, or one of the logical devices
"Cn:" discussed above.  On the other hand, directly executable script
files MAY be in directories on the path.

Within a command script you can give any command that Sili(Con:) would
accept from the Control Window -- even if the "X" command is invoked,
because once the arguments have been substituted the command list is
passed back to Sili(Con:) for execution.  However you should not nest
another script file name except as the last item in the sequence:
execution terminates at the first end-of-file encountered.  To invoke
another script file from within a script, use "X" explicitly.

Note that the "S:" directory is searched before the "C:" directory, so you
can have a script file that supersedes a DOS command with the same name.  If
the script references the DOS command itself it must use a full path name.
As an example, "S:ED" could contain:

        .k text
        run c:ed <text$text.temp>

This simply brings up the editor as a background process, keeping Sili(Con:)
available as well.


Appending Redirected Output
===========================

In addition to the normal CLI ">filename" convention for redirecting the
standard output of a command to a file, Sili(Con:) allows ">>filename".
In this case "filename" MUST already exist (or an error will be reported),
and output from the command will be appended to its current contents.
(As with the normal CLI, the redirection must immediately follow the
command name itself; this is a requirement of the DOS syntax.)

For example:

          dir >alldirs df0: opt a
          dir >>alldirs df1: opt a

gets one file containing a complete directory list of both your current
disks.


The Control Window
==================

Whenever the window labelled "Sili(Con:) is active, characters typed on the
keyboard will appear on the Command line.  If you enter a longer line than
can be accomodated in the window it will scroll left.  A command may have
up to 200 characters total (DOS limitation).  Typing a return will enter
the command for execution.

You can edit the Command line before execution using standard string gadget
conventions.  Left and right arrow keys move one character at a time left
or right.  Holding the shift key down while typing a left or right arrow
moves the cursor to that end of the line.  Backspace deletes successive
characters to the left, DEL deletes to the right.  In addition, holding
the Right Amiga key down while typing 'Q' restores the string to what it
was initially (this will be empty, unless you are re-editing a previous
command -- see below).  You can delete the whole string (and the Undo
buffer!) at any time with CTRL-X (not string-gadget standard).

When you execute a command with return it is also entered in the "History
List" displayed above the command line (unless it is a previous command
that is being re-executed unchanged).  You can retrieve the just-executed
command by typing the up-arrow once; further up-arrows retrieve preceding
commands one by one.  You can move back down the list again with the
down-arrow key.  A retrieved command can be executed unchanged by typing
return, or it can be re-edited before execution.  A maximum of 50 commands
will be kept in the history.  To see more of the history, use the sizing
gadget to expand the window.

Instead of using the arrow keys, you may click directly on a command
visible in the history window.  Clicking once retrieves it for editing.
Double-clicking executes it immediately.  (You can't execute the Command
line by double-clicking.  You can, however, reactivate the window by a
single click on this line.)

If you want to preserve a command -- perhaps partially completed -- in
the history list without actually executing it at that time, you can do so
by holding down the shift key and typing return.  To delete a command
from the list, move to that line with the arrow keys or the mouse and hold
down the Right Amiga key while typing DEL.

If you want to move the Control window to the back as you execute a command,
hold down the Right Amiga key as you type the return.  The command will
execute in the normal way, but the Control window will disappear.  You can
actually use Right-Amiga_Return at any time to push the Control window to
the back -- whether it is active or not.  If it isn't active, any characters
currently in the command line will remain there unexecuted; if it is, and
you want to get the window out of the way without executing anything, make
sure the Command line is empty first.  Once the window has been "put to
sleep" with Right-Amiga-Return, you can wake it up again by Left-Amiga-Return
as described in the next paragraph or by clicking the left mouse button
within it.

You can bring the Sili(Con:) window to the front and make it active at ANY
time by holding down the Left Amiga key and typing return.  Caution: if
you are not in the WorkBench Screen at the time, you won't see this happen;
you will have to switch to that screen with Left-Amiga-N.  Also, if
the Command line happens to be already active (because characters have
been typed while the window was active, for example) the Control window
will not immediately come to the front;  a safe way out of this is to
use shift-return to preserve and empty the Command line.

Any of the Interrupt combinations CTRL-C, CTRL-D, CTRL-E, OR CTRL-F that
you type when the Control window is active will be transmitted to the
running program, causing it to take whatever action it normally does in
that situation. (Unless the program takes some other course, Sili(Con:)
itself will eventually get any CTRL-D typed, and will then abort any
command script that might be in progress at the time.)

A "feature" of the current version (in the true programmer's sense -- it
appeared magically in the finished program...) is that typing Right-ALT
while holding the Right Amiga key down will freeze the screen when the
Sili(Con:) window is active.  To unfreeze it again, type the Amiga key
(other keys may have temporarily paralysing effects -- I said this was
a feature!).  Holding the LEFT Amiga key down and pressing Right-ALT will
only freeze the screen while it is depressed.


Sili(Con:) Messages
===================

Informational Messages:

  "running via `X' command"
    The command is a script file with arguments.

  "running script file directly..."
    The command is a script file that doesn't take arguments.

  "<programname> returned value <n>"
    The return code from the program was <n> (rather than the usual 0).

  "exceeded FAILAT setting"
    The return code was greater than the current value set by the
    FAILAT command.  If a command script is in progress, it is aborted.

  "**BREAK**"
    A CTRL-D interrupt was sent, aborting the command sequence.
    (Note that "**BREAK" is reported by some programs if CTRL-C is sent.)


Error Messages:

  "couldn't find <filename>"
    No file matching the specified command was found in either the
    assigned device list or the path.

  "Script file on path can't be EXECUTED"
    'X' (EXECUTE) doesn't know about the DOS 1.2 path.

  "This file needs to be run with `X'"
    A script file being run directly was found to contain a line
    beginning with a period.

  "couldn't load <programname>"
    A program file was apparently found, but couldn't be loaded.
    You will normally only get this message because of a bug in the
    DOS 1.2 RAM: handler.  AVOID having RAM: in the path or assigned
    as "Cn:" (a subdirectory, such as "RAM:C", is all right).

  "Command string too long!"
    The command had more than 200 characters.

  "already redirected!!"
    More than one Input Redirection ("<"), or more than one Output
    Redirection (">" or ">>"), was specified in one command.

  "couldn't open `<filename>'!!"
    The <filename> specified as a redirection argument couldn't be
    opened -- for instance if the mode was "append output" (">>") and
    the file doesn't already exist.

  "NO SPACE FOR STACK -- ABORTING COMMAND!!"
    Memory is too full to allocate stack space for the program to
    be run.  (Depending on the situation, you may not be able to run
    anything else either at this point.  If all else fails you can
    click Sili(con:)'s Close gadget to regain its space.)




Distribution
============

The program Sili(Con:) and this documentation are

                  Copyright (C) 1986 by Peter J. Goodeve

You may copy it freely under the terms below, but it is NOT Public Domain.
All Rights are reserved by the author.

Distribution to other parties is permitted provided that the distributor
makes NO charge for such distribution, except that Bona Fide User Groups,
or such other individuals or groups that have been notified in writing
of permission to do so by the author, may impose a small charge to cover
copying and materials costs.  This Document with its Copyright notice and
distribution permissions MUST accompany all copies of the program.

Many months of effort have gone into its development, so if you use it
you are strongly urged to send a donation to the author (please!):

         Peter Goodeve
         3012 Deakin Street, #D
         Berkeley, California 94705

$25 is suggested as the standard contribution, but whatever you feel is
right.  Remember though that future development of this program depends
almost entirely on your response, so if you like it... RESPOND!
[I begin to feel like a PBS Pledge Night pitchperson -- but I guess
the theory is pretty much the same, anyway.]

There's even a premium.  If I have your address and your $25, I will send
a disk with the first significant update.  Also if you have suggestions or
comments please send them.  They will be heeded.  When you send your
donation, please include the version number of the program (in the CLI
window when it starts up -- e.g. [8611.2]) so that I can keep track of
things.

Coming back to future developments, I have in mind some significant
extensions for "Second Sili(Con:)" -- things like managing multiple CLI
processes (in their own windows) from a single control window, and an
advanced type of environment variable -- that will take full advantage of
the fundamental capabilities of our favorite machine.  When, how, and even
if, this is distributed will depend on funding.  (It won't be a free
update, though.)  So don't procrastinate... [Hey, PBS, how'm I doing?]

And finally, of course, because you are not asked to pay for this program
unless you find it suitable,   NO WARRANTY OF ANY KIND IS PROVIDED,
TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW.

THE PROGRAM IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK
AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU, THE USER.
SHOULD THE Sili(Con:) PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL PETER J. GOODEVE, AND/OR
ANY OTHER PARTY WHO MAY LEGALLY DISTRIBUTE THIS PROGRAM, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL,
INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF OR INABILITY
TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A FAILURE OF
THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAM), EVEN IF YOU HAVE BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER
PARTY.